TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/(A)TB/(A)TBE.ADF/Utility/ReadMe_DS14

Text File | 1989-09-12 | 28KB | 639 lines

                        D i s k S a l v

                 AmigaDOS Disk Salvage Program

                 Copyright 1989 by Dave Haynie

                  Version 1.40 for AmigaOS 1.3


INTRODUCTION

    DiskSalv V1.40 is a disk recovery program for all Amiga file
system devices that use either the AmigaOS V1.2/V1.3 Standard File
System or the AmigaOS V1.3 Fast File System. DiskSalv will scan a bad
disk volume for anything that can be recovered, and will restore
these items to any AmigaDOS volume. It does not make any attempt to
fix the bad device in place; thus, any file that can't be restored
with DiskSalv might possibly be restored with an alternate method.

    DiskSalv V1.40 fixes all bugs found in DiskSalv V1.32 (there
might still be bugs, but no one found them...).  There were two main
V1.32 bugs. First of all, a bug in the processing of logical vs.
physical volumes caused DiskSalv's file size checking to get switched
off at the wrong times. This caused OS requesters to show up when
disk volumes got full, something DiskSalv was not supposed to let
happen. The sizing check now works properly, and only gets switched
off automatically when output is directed to RAM:. The other DiskSalv
V1.32 bug was incorrect handling of circular directories, which would
usually result in a crash during the scanning process. DiskSalv will
now disallow a child of a directory to be added as that directory's
parent. One minor fix was also added to the scanning routine to allow
^C cancellation of the scan when the QUICK or LOMEM options are
selected.

    DiskSalv V1.40 also contains some enhancements. It no longer
allocates memory in tiny little chunks that can cause RAM
fragmentation, but instead allocates a few large chunks of memory.
It also uses much less stack memory, so it will actually salvage a
typical floppy with the standard 4K stack of the Amiga shell. The
DiskSalv FORMAT routine, which would crash in some cases, has been
completely removed. When formatting is requested now, DiskSalv will
call the AmigaDOS Format command to actually do the work. It looks
for Format in the current directory, then it checks the "SYS:System"
directory. DiskSalv V1.40 MUST have access to both Format and
L:Disk-Validator in order to format a disk.  The START and STOP
options are now more robust; START can be given a negative relative
offset, STOP knows about the ROOT now, and either can express disk
size as a percentage instead of in blocks, if desired.

    Finally, DiskSalv has some new options, which will be described
in greater detail later on. The first of these is the NODOS option,
which solves a problem that sometimes comes up when you have a disk
that can hang or crash to OS. Another new option is the FILE option,
which allows you to specify a filename pattern to match against
during the scanning phase. Finally, the LOMEM option drops DiskSalv
memory usage to a minimum, at the expense of some speed and features.


1. THE BASICS OF DISKSALV V1.40

    DiskSalv V1.40 (from here on referred to as "DiskSalv") is a
program designed to "salvage" any files and directories from a
damaged AmigaDOS file system device to a good one. DiskSalv is run
from an Amiga CLI, and in the simplest case is used very much like
the AmigaDOS "DiskCopy" program. For example, to recover files from a
bad disk in DF0: and restore them on a good disk DF1:, the user will
type:

    1> DiskSalv FROM DF0: TO DF1:

Here the "FROM" and "TO" keywords are fully optional if the ordering
of the input and output devices is kept INPUT OUTPUT. The following
line would also achieve the same result:

    1> DiskSalv TO DF1: FROM DF0:

In either case, DiskSalv will immediately print to the shell's
screen:

    DiskSalv V1.40 Copyright ⌐ 1989 by Dave Haynie

    Salvage FROM Device DF0: TO Path DF1:

      DEVICE     =    trackdisk.device   (DF0:)
      UNIT       =        0    FLAGS      =        0
      HEADS      =        2    SECTORS    =       11
      LOCYL      =        0    HICYL      =       79
      LOBLOCK    =        0    HIBLOCK    =     1759
      RESERVED   =        2    MEMTYPE    =        3
      ROOT BLOCK =      880    DISK SIZE  =     1760

    Scan Range: START 2, STOP 1759, Expecting Standard FileSystem

    Should I continue [Y]

At this point, a simple RETURN entered will start up the recovery
process, while an "N" followed by a RETURN will abort the recovery.

1.1 The Scan Phase

    If we proceed with the recovery, DiskSalv will start the first
phase of it's recovery. At this point, the input device will be
scanned from start to finish (blocks 2 though 1759). DiskSalv is
looking for valid AmigaDOS file or directory blocks. A small
Intuition window called "DiskSalv Scan" will open on the Amiga's
WorkBench screen. There are three columns in this window, BLOCK,
NODES, and TYPE. As each block is read, it's number is displayed
under BLOCK. This happens pretty quickly; ordinarily, there's no need
to examine individual block numbers anyway. The TYPE field indicates
whether the block is a file (FILE), root directory (ROOT), user
directory (UDIR), data block (DATA), unused block (FREE), unknown
block type (????), or bad block (ERR!). Note that under the new
AmigaDOS V1.3 Fast FileSystem, there's no way to distinguish between
DATA and FREE blocks during a scan, so these are always displayed as
unknown blocks. The final field, NODES, indicates the number of user
directory or file blocks that have been located so far.

    The other feature of this phase is the file list, which takes
place on the screen. The shell window will indicate "Building
Directory Map...", and the name of each directory and file that's
found will be displayed under this heading. Note that at any time
during this scanning phase, clicking the Scan Window close gadget
will abort the program. If the QUICK or LOMEM operations are
selected, no visual account of the block scan number will be
displayed.

1.2 The Directory Resolution Phase

    The next phase is usually a very short one. The scanning window
will disappear, and the shell window will indicate that DiskSalv is
"Resolving Stray Directories...". During the scanning phase, when
DiskSalv finds a file block, it attaches it to a directory in it's
directory list. To make the scan phase fast, however, DiskSalv only
does a single linear pass over the input disk during that phase. If
the parent directory for a file or subdirectory isn't available,
DiskSalv makes a dummy directory for it in it's directory list.

    Normally, all of those dummy directories get changed into normal
ones as they are found in the scan. However, there are some DiskSalv
modes (covered later) that may result in only a partial scan being
performed. In this case, valid directory entires may be outside of
the scanning range. In order to get the proper names of such
directories, the resolution phase goes through the directory entires
in it's dummy list and tries to find real directories to match them.
If a directory can't be found, it was probably located on a bad
block. That's no problem, all that's lost is the name of that
directory, not any of it's contents.

1.3 The Directory Pruning Phase

    The next pass happens purely in memory, and it attempts to remove
any empty directories from the directory list. There are rarely any
empty directories that need to be restored, and there are some
DiskSalv options that tend to force a number of empty directories to
be created in the directory list. This pass can be overridden if
 empty directories are deemed important.

1.4 The Disk Salvage Phase

    In this next phase, the disk structure is actually restored to
the output device. This proceeds until stopped via ^C, or until the
output device is full. If the output device fills up, a new one can
be inserted if the device supports removable media. The most common
form of this would be floppy disk.

    There are certain output devices which may not return proper
volume sizing information through AmigaDOS. For instance, the RAM:
device always says it's full. A DiskSalv option allows output size
checking to be turned off, and it's automatically selected if the
output device is RAM:.

    DiskSalv uses normal AmigaDOS I/O routines to re-create the
recovered files. Thus, it may restore to a subdirectory instead of
the root of a device. If a subdirectory is specified that doesn't
exit, DiskSalv will create it. Similarly, DiskSalv may output to a
logical volume name instead of a device name.

    On occasion, a file will be found that DiskSalv considers to be
suspect. The screen output will indicate the problem, but that tends
to scroll by very quickly. DiskSalv will now add a FileNote to any
file that it suspects, indicating its concern. This option can be
overridden.

    Finally, there are occasions under which there may be file name
collisions.  If the output device has a file by the same name as one
that's on the input device, such a collision occurs. DiskSalv won't
overwrite files. Instead, the colliding file is renamed before it is
rebuilt. An extension is added to it, starting at "-0" and going on
up to "-100" as collisions continue to occur.


2. DISKSALV REFERENCE GUIDE

    The DiskSalv program is run and controlled completely via
command-line arguments. It should run without problem from all Amiga
shell programs; it currently can't be run from the WorkBench.

2.1 Command-Line Options

    There are quite a few options in DiskSalv that'll modify in
various ways the recovery action described above. The syntax for the
DiskSalv command line is given as:

Usage: DiskSalv [FROM] InDev: [TO] OutPath [[NO]FFS] [QUICK]
[NOCHECK] [NOTAG] [FORMAT] [LOMEM] [NODOS] [NOTD] [FILE pattern]
[NOPRUNE] [START [-]num[%]|ROOT] [STOP [+]num[%]|ROOT] [ASK] [INFO]
[MASK [a|A][r|R][w|W][e|E][d|D][p|P][s|S]]

In each case, text in brackets ("[]") indicates an optional
parameter, text outside of brackets indicates a required parameter,
and "|" indicates a choice of parameters. The options are: ASK

    This options allows the Disk Salvage pass to proceed
    interactively instead of automatically. The user is prompted at
    each file or directory. A reply of 'Y' will recover that file or
    move into that directory, a reply of 'N' will skip that item.
    Replying '?' will list all the valid options.  A reply of 'A'
    will recover everything left at the current directory level; a
    reply of 'U' will skip everything left at the current directory
    level.  Finally, a reply of 'Q' will quit the program completely.

[NO]FFS
    This allows the disk's filesystem to be selected.  Normally,
    DiskSalv can tell the difference between a fast and standard
    filesystem disk, and will act accordingly.  However, if that disk
    is badly damaged, this assumption may be incorrect.  In such a
    case, DiskSalv will usually assume standard filesystem.  If it's
    assumption is wrong, the filesystem can be forced with these
    options.

FILE pattern
    Cause the DiskSalv scanner to only record files that match the
    given pattern, which is a standard AmigaDOS filename pattern.
    This pattern specification has no effect on any directories that
    might be examined, since DiskSalv won't necessarily know the
    names of all directories until the scan phase is complete.

FORMAT
    This forces the output device to be formatted before any output
    files are directed to it. If the output device isn't a device,
    but instead a handler, DiskSalv will return an error message if
    this option is selected; it only knows how to format devices.
    DiskSalv     will also offer the option of formatting the output
    device if it fills up during a recovery. An important note on all
    DiskSalv formatting options -- the disk validator and the Format
    command MUST be accessible for the format to work. If they're not
    available, DiskSalv will refuse to format an output disk.  If you
    specify the FORMAT option on the command line, DiskSalv will
    return with an error message if these programs can't be located.
    If you don't specify FORMAT and they can't be found, a warning
    will be issued. If you go on from there, everything will work OK,
    but you'll never be offered the FORMAT option. The best way to
    insure that it's present is to have the L: directory with the
    disk validator in it on the same disk that DiskSalv is run from,
    and the Format command in the same directory as DiskSalv. It may
    be necessary to Assign L: to that disk. Depending on the shell
    you use to launch DiskSalv, the return code of the Format command
    it spawns may not be correct. DiskSalv will notify you if it
    thinks a format didn't work; an "Ignore" option here lets you
    continue on if you believe it did, indeed, work. Finally, if you
    have the CNC: device from Bill Hawes' mounted, Format will use
    that for it's display instead of a CON: window.

FROM InDev:
    This option allows an input device to be specified.  The input
    device must be a real device, not a path specification. The FROM
    keyword is optional, but can be used to allow FROM and TO
    specifications to be given in any order.

INFO
    The INFO option lists some information about the program, it's
    distribution, bug reporting, and other stuff.  It should be
    specified in the command line without any other options.

LOMEM
    This tells DiskSalv to use as little memory as it can get away
    with. As with the QUICK option, no scanning display is generated.
    However, some operations may take longer than the norm.  DiskSalv
    normally uses 2 bits per device block, 8 bytes for each file
    entry loaded into its file lists during a scan, and 52 bytes for
    each directory entry. This option, among other things, changes
    that fixed block usage to 1 bit per device block, lowers the
    chunk size used by the memory allocator, and lowers the maximum
    length allowed for path names.

MASK [a|A][r|R][w|W][e|E][d|D][p|P][s|S]
    This options allows the user to specify a protection bit mask as
    a filter. The supported bits are "A" for Archive, "R" for Read,
    "W" for Write, "E" for Execute, "D" for Delete, "P for Pure, and
    "S" for Script. Specifying the bit in lowercase indicates a mask
    for that bit not set, a bit in uppercase indicates a mask for
    that bit set. For example, specifying "MASK a" will scan for only
    those files that don't have the archive bit set; "MASK WD" will
    scan only for those files with Write and Delete permission
    enabled. Any bits not specifically MASKed can be in either state.

NOCHECK
    This option prevents the output device's size from being checked.
    Normally this would only be used with a device that doesn't
    properly report it's size, and it's automatically invoked with
    output to RAM:.

NODOS
    Prevents DiskSalv from accessing DOS at any level on the input
    disk.  Normally, DiskSalv does a DOS inhibit on the input disk to
    prevent any other process from modifying the disk during the
    recovery process, since such modifications could damage the disk
    or interfere with the recovery process. This option is best used
    when trying to recover from a disk that can crash DOS when
    accessed.

NOPRUNE
    This option prevents the directory pruning phase from taking
    place. If the input device contains empty directories that must
    be restored, use this option.

NOTAG
    This option prevents DiskSalv from tagging possibly damaged files
    with a FileNote explaining it's concern.

NOTE
    DiskSalv does some special optimizations when it's recovering
    from a floppy disk device based on the "trackdisk.device" driver.
    While there's currently no real use for this option, a future
    version of "trackdisk.device" might possibly not work with these
    enhancements. This option will turn the enhancements off, making
    a recovery from the "trackdisk.device" work exactly like any
    other recovery.

QUICK
    This option performs a quick scan.  The scan speed is improved by
    not displaying the block number and type information for every
    block.  This doesn't make as much difference as it did in the
    earlier versions of DiskSalv; the "DiskSalv Scan" window routine
    has been greatly sped up this display.

START [-]num[%]|ROOT
    This option allows the scanning routine to start at any place on
    the input device. This position is either given as a decimal
    block number, a percentage of the disk, or as the string ROOT.
    The start value is normally an absolute disk position, but is
    instead relative to the STOP position if the "-" option is
    supplied. If relative values for both START and STOP are given,
    they're taken to be relative from the disk's root. Since many
    files are clustered after the directory root on most disks, it's
    often possible to get many of a disk's files back starting the
    scan there instead of at the start of the disk.

STOP [+]num[%]|ROOT

    This option allows the scanning routine to stop at any place on
    the input device. This position is either given as a decimal
    block number, a perentage of the disk, or as the string ROOT.
    The stop value is normally an absolute disk position, but is
    instead relative to the START position if the "+" option is
    supplied. If relative values for both START and STOP are given,
    they're taken to be relative from the disk's root.

TO OutPath
    This option allows an output path to be specified.  The output
    device can be any valid AmigaDOS file device specification. The
    TO keyword is optional, but can be used to allow FROM and TO
    specifications to be given in any order.

2.2 Input Device Specification

    DiskSalv requires a DOS name specification for its input device.
Such a name is automatically created by the operating system for each
3.5" disk drive attached, and for some hardware add-ons during
automatic device binding process initiated by the AmigaDOS
BindDrivers command. Other DOS names are created by the Mount command
and the MountList file.

    On occasion, a few problems show up in this theory. First of all,
a device like a hard disk may store its physical layout, necessary to
create a DOS node, on the disk itself.  If the disk is damaged, this
special information may not be available any longer, and as a result,
the hard disk's device driver won't be able to create a DOS node.  In
this case, the user will have to create a MountList entry by hand for
the device. This device will then be Mount-ed, and DiskSalv can take
over from there.

    The other problem I've found is that allowing AmigaDOS to access
a bad volume can occasionally result in a system crash.  With a
mounted volume, that's no big problem; AmigaDOS won't usually try to
access the device, or even load the device driver, until that drive
is actually accessed. It's OK, and in fact required by DiskSalv, to
just "Mount" the device. In some cases, the File System (especially
FastFileSystem) will try to access a disk as its being initialized.
This can cause a problem if the disk is damaged in such a way as to
violate important assumptions the File System makes about the disk.
The NODOS options will circumvent this by eliminating any File System
level access of the device by DiskSalv. Floppies can be a bit more
dangerous. A floppy will start up the File System's validator nearly
as fast as it's inserted. The proper damage could crash or lockup the
machine, but there's no way to prevent the floppy's File System, or
the DiskChange interrupt from the trackdisk.device, from being sent
until DiskSalv has been started. Once DiskSalv reaches the "Should I
Continue [Y]" prompt, such damaged floppies can be safely inserted.
 It's important here not to use the NODOS option.


3. WARNINGS AND ERRORS

    DiskSalv produces a variety of error messages when it thinks
something is wrong. These fall into two basic classes. First of these
are fatal errors that may result from the program being run
incorrectly in some way. This results in the program terminating with
a message of some kind. The second class are warning messages that
result due to some condition DiskSalv reacting to, but don't actually
stop the program from executing.

3.1 Fatal Errors

"Illegal Command Line Option"

    You typed an invalid option at the cli. DiskSalv options are case
independent, but must match exactly letter for letter.

"DiskSalv User Abort"

    You terminated DiskSalv with a ^C or other user-invoked abort.

"Must have input and output objects"

    You didn't specify both a "TO" and a "FROM" device on the command
line.  There are no default input or output devices.

"Input DEVICE Not Mounted"

    The input device specified does not appear in the system device
list.  It's possible that you just forgot to mount the device.

"START/STOP flag conflict"

    This is usually the result of specifying a START block greater
than your STOP block. DiskSalv won't scan a disk backwards. It's also
possible that you specified an out-of-range block.

"Out of Memory"

    If DiskSalv can't get the memory it needs, this error message
will result.  This will only happen if it can't get memory that's
absolutely necessary. On systems with lesser memory, some features
may no be invoked if the memory in the system gets too low, but this
will not result in an error message.

"DiskSalv cannot format output device"

    You have requested the FORMAT option for an output device that
DiskSalv doesn't know about, format-wise.  DiskSalv only knows how to
format standard devices, like "trackdisk.device", "ramdrive.device",
"hddisk.device", etc.

"Input and output object collision"

    You've specified the same device for both input and output;
that's not permitted.

"Cannot get 'intuition.library'"

    For some reason, the inutition.library cannot be opened by
DiskSalv.

"Cannot get 'dos.library'"

    For some reason, the dos.library can't be opened by DiskSalv.

"Cannot create message port"

    DiskSalv can't create the message port it needs for using the
input device driver directly.

"Cannot find the disk validator"

    You have requested the FORMAT option for an output device, but
DiskSalv can't find the disk validator necessary to validate that
device after formatting it.  The disk validator is found in the "L:"
directory. This mistake is most commonly made when recovering your
normal system disk.

"Cannot find the disk formatter"

    You have requested the FORMAT foption for an output device, but
DiskSalv can't find the disk format command necessary to format that
device. The format command may be located in the current directory or
on SYS:System. This mistake is most commonly made when recovering
your normal system disk.

"Cannot create I/O port"

    DiskSalv can't create the I/O port it needs for using the input
device driver directly.

"Cannot set up break trap routine"

    You'll probably never see this one, but it could be an early
indication of severe low memory conditions.

"Invalid AmigaDOS file pattern specified"

    You've specified the FILE option, but supplied an invalid pattern
string.

3.2 Run-Time Warnings

"No formatting, cannot find disk validator"

    The disk validator isn't around, but since you may not need it,
we go ahead.  If this warning is printed, you lose the option to
format output disks during a recovery.

"No formatting, cannot find disk formatter"

    The disk format command isn't around, but since you may not need
it, we go ahead.  If this warning is printed, you lose the option to
format output disks during a recovery.

"Resolving link conflict # <-> #"

    This warning results from a condition on there input disk where,
for a data block on that disk, the block's file header link and block
chain link don't match. DiskSalv tries to resolve this conflict by
choosing the best of the two, but it is possible that neither is the
proper choice. This will only happen with Standard FileSystem; there
is no data block chain link in the Fast FileSystem.

"Bad Extension Block - No More Link Check"

   Under Standard file system, an Extension block can't be found. We
can still proceed. Under Fast FileSystem, this could never happen.

"Possible Disk Fault, File may be incomplete"

    This is printed for each file that was recovered from a partially
bad trackdisk sector.

"Disk Fault, File may be incomplete"

    Means pretty much the same thing as the last one, only that this
time we're certain that a block be sure about that.

"Double Disk Fault, File truncated"

    There have been serious errors in the current file, to the extent
that the file may not be recoverable.

4. KNOWN BUGS

    None


5. THE FUTURE OF DISKSALV

    The next release of DiskSalv is already in development, so don't
consider this a dead end. I am actively seeking any and all feedback
on the subject. Please, if there's something that doesn't work right,
or something DiskSalv isn't doing that you'd like to see it do in the
future, please let me know. I can't put it in there if I don't think
of it.


6. LISCENCING AND DISTRIBUTION

    This program may be distributed free of charge, provided that no
extra restrictions are placed on it. Nominal charges for copying or
on-line services are permitted provided that they are only for those
services. This program was written to help out the Amiga community,
not to make folks feel guilty. Thus, no payment is required for its
use.

    I certainly don't mind donations, including donations of bug
reports, comments, suggestions for future enhancements, macadamia
nuts, or even software. BUT PLEASE, DON'T SEND ME ANY PIRATED
SOFTWARE. YOU WILL REGRET IT. I wouldn't have thought it necessary to
mention this, given the quality of the people working with the Amiga
(intelligent folks recognize superiority). But I received several
such disks from users of previous DiskSalv releases. They all came
from out of the country, and served me just fine as blank disks. But
it really annoys me to see this. Anyway, at least until the end of
June I can be reached at:

                Dave Haynie
        645 Allen Avenue
        Gibbstown, NJ 08027

        BIX:    hazy
        PLINK:  D-DAVE H
        USENET: ...!cbmvax!daveh

My electronic addresses changing.  If you really want to send money,
I'm not going to refuse it or anything, but you may instead consider
sending a donation instead to:

        GreenPeace
        1436 U Street NW
        Washington, DC 20009

Tell me about it, and I'll include you in my registration files. I
know  you don't get rich from "ShareWare"; while I got some donations
for DiskSalv going all the way back to the beginning (which I'm
certainly very grateful for), they didn't pay enough for me to try
treating DiskSalv as a money-making venture, rather than just a
hobby.  I wrote DiskSalv V1.40 because it's needed, because I like to
write programs in my spare time, and for my ego -- if I didn't write
DiskSalv V1.40, someone else out there is going to write a better
disk recovery program, and then mine won't be the best any more.
 Don't know if DiskSalv V1.40 necessarily is the best these days, but
I know it's the best DiskSalv so far. Anyway, while DiskSalv's saving
your disks, maybe the folks at GreenPeace will get a little extra
money to save a few more important things, like clean air, clean
water, and wildlife.


7. CREDITS AND THANKS

    My thanks go out to the Amiga community in general, for all the
good stuff they're doing.  Special thanks to:

    - Well, I switched back to Lattice on this one.  Nice going,
      Mr. Toebes.
    - Bill Hawes, as always, for AREXX and WShell.
    - The Arthur Guinness Company.
    - The gang at PLINK for continued help.
    - Joseph Armstrong, for restoring my faith in humanity by sending
      me the first disk I've received from outside the USA in
      response to DiskSalv that wasn't full of pirated stuff.
      Ripper!
    - Folks who've found the latest round of bugs, the number of
      which actually seems to be shrinking; or supplied enhancement
      ideas (thus opening up room for new bugs...) including:
      Greg Berlin, Bruce Dawson, Joanne Dow, Marco Papa, D.C. Murphy,
      Steve Rosenthal


                -Dave Haynie
                 April 2, 1989